QuickTime 4 Reference

Creating a Tween Sequence

"Single Tweens and Tween Sequences" discussed tween sequences, in which different tween operations of the same type may be applied sequentially. The type kTweenSequenceElement specifies an entry in a tween sequence. Its parent is the tween QT atom container (which you specify with the constant kParentAtomIsContainer ).

The ID of a kTweenSequenceElement atom must be unique among the kTweenSequenceElement atoms in the same QT atom container. The index of a kTweenSequenceElement atom specifies its order in the sequence; the first entry in the sequence has the index 1 , the second 2 , and so on.

This atom is a leaf atom. The data type of its data is TweenSequenceEntryRecord , a data structure that contains the following fields:

endPercent , a value of type Fixed that specifies the point in the duration of the tween media sample at which the sequence entry ends. This is expressed as a fraction; for example, if the value is 0.75, the sequence entry ends after three-quarters of the total duration of the tween media sample has elapsed. The sequence entry begins after the end of the previous sequence entry or, for the first entry in the sequence, at the beginning of the tween media sample.
tweenAtomID , a value of type QTAtomID that specifies the kTweenEntry atom containing the tween for the sequence element. The kTweenEntry atom and the kTweenSequenceElement atom must both be child atoms of the same tween QT atom container.
dataAtomID , a value of type QTAtomID that specifies the kTweenData atom containing the data for the tween. This atom must be a child atom of the atom specified by the tweenAtomID field.

Listing 19 shows how to create a tween sequence.

Listing 19 Creating a tween sequence



 
OSErr CreateSampleSequencedTweenContainer( QTAtomContainer container,

    TimeValue duration, QTAtom *newTweenAtom )

{

    OSErr               err = noErr;

    QTAtomContainer     dataContainer = nil;

    OSType              tweenerType;

    QTAtom              sequenceAtom, tweenAtom;

    TimeValue           offset;

    Handle              result;

    QTAtomID            tweenAtomID, dataAtomID;

    Fixed               endPercent;

    

    err = QTRemoveChildren( container, kParentAtomIsContainer );

    if ( err ) goto bail;



    tweenerType = kTweenTypeAtomList;

    offset  = 0;



    err = AddSequenceTweenAtom( container, kParentAtomIsContainer, 

                                1, &sequenceAtom );

    if ( err ) goto bail;

    

    offset = 0;



 
    err = AddTweenAtom( container, sequenceAtom, 1, tweenerType, offset,

                        duration, 0, 0, nil, &tweenAtom );

    if ( err ) goto bail;

    

    // add first data atom (id 1) to tween atom

    dataAtomID = 1;

    dataContainer = CreateSampleAtomListTweenData( dataAtomID );

    if ( ! dataContainer ) { err = memFullErr; goto bail; }



    err = AddDataAtom( container, tweenAtom, dataAtomID, 0, nil,

                        dataContainer, 0, nil );

    if ( err ) goto bail;

                   

    QTDisposeAtomContainer( dataContainer );

    

    // add second data atom (id 2) to tween atom

    dataAtomID = 2;

    dataContainer = CreateSampleAtomListTweenData( dataAtomID );

    if ( ! dataContainer ) { err = memFullErr; goto bail; }



    err = AddDataAtom( container, tweenAtom, dataAtomID, 0, nil,

                        dataContainer, 0, nil );

    if ( err ) goto bail;

                   

    QTDisposeAtomContainer( dataContainer );



    // now create a sequence with four elements; the first three are data

    // atom 1, the last is data atom 2

    endPercent = FixDiv( Long2Fix(25), Long2Fix(100) );

    tweenAtomID = 1;

    dataAtomID = 1;

    err = AddSequenceElement( container, sequenceAtom, endPercent,

                                tweenAtomID, dataAtomID, nil );

    if ( err ) goto bail;



    endPercent = FixDiv( Long2Fix(50), Long2Fix(100) );

    tweenAtomID = 1;

    dataAtomID = 1;

    err = AddSequenceElement( container, sequenceAtom, endPercent,

                                tweenAtomID, dataAtomID, nil );

    if ( err ) goto bail;



    endPercent = FixDiv( Long2Fix(75), Long2Fix(100) );

    tweenAtomID = 1;

    dataAtomID = 1;

    err = AddSequenceElement( container, sequenceAtom, endPercent,

                                tweenAtomID, dataAtomID, nil );

    if ( err ) goto bail;



    endPercent = FixDiv( Long2Fix(100), Long2Fix(100) );

    tweenAtomID = 1;

    dataAtomID = 2;

    err = AddSequenceElement( container, sequenceAtom, endPercent,

                                tweenAtomID, dataAtomID, nil );

    if ( err ) goto bail;

bail:

    if ( err ) {

        if ( container )

            QTRemoveChildren( container, kParentAtomIsContainer );

        *newTweenAtom = nil;

    }

    else

        *newTweenAtom = sequenceAtom;

}